home *** CD-ROM | disk | FTP | other *** search
/ Aminet 28 / Aminet 28 (1998)(GTI - Schatztruhe)[!][Dec 1998].iso / Aminet / mus / misc / mp3asm.lha / mp3asm.doc < prev    next >
Encoding:
Text File  |  1998-09-14  |  7.4 KB  |  209 lines
  1.  
  2. README for mp3asm
  3. =================
  4.  
  5. License:  Unlimited use for private purposes permitted, as long
  6.           as you don't remove author information, license and
  7.           disclamier.  Commercial / for-profit use requires my
  8.           explicit permission.
  9.  
  10. Disclaimer:  This software is provided "as-is".  Whatever you
  11.              do with it, it's at your own risk.  I can not be
  12.              held liable for any damage resulting from this
  13.              software.  If you don't accept this, don't use the
  14.              software.
  15.  
  16.  
  17. IMPORTANT NOTES
  18. ---------------
  19.  
  20. This software is currently in alpha testing stage.  That means
  21. that it might not work as expected or described, and in fact it
  22. might not work at all.  Maybe it also causes your computer to
  23. explode and kill your cat.  See the disclaimer above.
  24. Of course, it is also possible that this software works fine.
  25.  
  26. Also note that syntax and semantics of command line options,
  27. format of output messages and other things may change in future
  28. versions.  And they most probably _will_ change.
  29.  
  30.  
  31. USING
  32. -----
  33.  
  34. Type "mp3asm" without arguments to see a short online help.
  35. Basically, mp3asm operates in three different modes:
  36.  
  37. 1. Verify mode
  38.  
  39.    This mode can be used to check whether an mp3 file is ok or
  40.    not.  Just type:
  41.  
  42.       mp3asm -v myfile.mp3
  43.  
  44.    Any errors encountered will be printed to stderr, along with
  45.    other information.  Note that the absence of error messages
  46.    does _not_ mean that the file is guaranteed to be compliant
  47.    with the MPEG audio specification.
  48.  
  49.    Do not specify more than one file in verify mode -- the
  50.    result will most probably not be what you expect.  (Tech
  51.    info:  mp3asm tries to read in all files at once, merge them
  52.    together internally and build a new MPEG stream from it,
  53.    which can cause errors even though the single files are
  54.    correct).
  55.  
  56.    You should use the -v option to make mp3asm a bit more
  57.    verbose.
  58.  
  59. 2. Fix mode
  60.  
  61.    This mode can be used to fix broken mp3 files.  It works
  62.    like verify mode, but in addition you specify an output file
  63.    using the -o option:
  64.  
  65.       mp3asm -v broken.mp3 -o fixed.mp3
  66.  
  67.    It will then read in the broken file, throw away everything
  68.    that looks broken, and writes the remaining data to the
  69.    specified output file.  Note that you can specify the same
  70.    name for input and output file, since mp3asm won't write
  71.    any output until all input files are read and analysed --
  72.    however, this is a bit risky, because you will lose the
  73.    original file, even if fixing the mp3 stream fails for some
  74.    reason.
  75.  
  76.    You can specify "-" as output file to write to stdout.
  77.  
  78.    Note that there may be still errors left inside the actual
  79.    frame data -- there is no way to find such errors without
  80.    completely decoding the audio stream, which is beyond the
  81.    scope of mp3asm.  In such a case you can use a decoder to
  82.    find out which frames are broken, for example:
  83.  
  84.       mpg123 -ytvvv broken.mp3
  85.  
  86.    The you can use the assemble mode of mp3asm to cut out the
  87.    broken frames, or replace them with other frames (although
  88.    the latter is very tricky).
  89.  
  90. 3. Assemble mode
  91.  
  92.    Using this mode (which is where the name mp3asm comes from)
  93.    you can cut parts from mp3 files and re-assemble them to a
  94.    new mp3 stream.  The simplest thing you can do is to just
  95.    concatenate multiple mp3 files:
  96.  
  97.       mp3asm file1.mp3 file2.mp3 file3.mp3 -o new.mp3
  98.  
  99.    It will read the specified files, build a new valid mp3
  100.    stream and write it to the specified output file.  Note that
  101.    the input files should not be broken -- if they are, use the
  102.    fix mode of mp3asm on the individual files first.
  103.  
  104.    Important note:  All the input files _must_ have compatible
  105.    frame parameters.  That means:  same bitrate, same sample
  106.    frequency, same stereo mode, same protection flags etc.
  107.    If those parameters are not the same, the result will not be
  108.    what you expect.  (Tech info:  mp3asm has to produce an mp3
  109.    stream with uniform frame parameters.  If the input frames
  110.    don't have the same parameters, mp3asm has to throw away
  111.    those frames which are in the minority, because it's not
  112.    possible to change parameters like bitrate, sample frequency
  113.    etc. without completely decoding/recoding the stream.  In
  114.    other words, mp3asm has to ignore the smallest of the input
  115.    files.)
  116.  
  117.    If you don't want to use an entire mp3 file as input, you
  118.    can specify a part of it using the -s (skip) and -n (number)
  119.    options.  The smallest unit in a stream is a "frame", which
  120.    is about 1/40 second for 128 kbits, 44.1 kHz files (to be
  121.    exact: 32/1225 second).  Example:
  122.  
  123.       mp3asm -s 10 -n 5 a.mp3 -s 20 -n 3 b.mp3 -o z.mp3
  124.  
  125.    It will skip the first 10 frames in a.mp3, then read 5
  126.    frames, then skip the first 20 frames in b.mp3 and read
  127.    3 frames.  The output file z.mp3 will contain 8 frames:
  128.    frames 10 - 14 from a.mp3, and frames 20 - 22 from b.mp3
  129.    (the first frame is numbered 0).
  130.  
  131.    The default is "-s 0" (don't skip frames) and "-n -1" (read
  132.    till end of file), i.e. files will be read completely by
  133.    default.  Note that the -s and -n options affect _all_ input
  134.    files specified after them.  Thus:
  135.  
  136.       mp3asm -s 30 -n 5 a.mp3 b.mp3 c.mp3 -o z.mp3
  137.  
  138.    Will read frames 30 - 34 from a.mp3, b.mp3 and c.mp3, so the
  139.    output file z.mp3 will contain 15 frames.  Another example:
  140.  
  141.       mp3asm a.mp3 -s 5000 a.mp3 -o z.mp3
  142.  
  143.    This will read the complete file a.mp3, then append the
  144.    ending (starting at frame 5000 in this case), so the frames
  145.    from 5000 to the end will occur twice in succession in the
  146.    output file z.mp3.
  147.  
  148.    Hint:  mpg123 also has options to skip frames (-k) and to
  149.    decode only a limited number of frames (-n), so you can use
  150.    it to find the exact position for extracting frames with
  151.    mp3asm.  If you make mpg123 more verbose (-vvv should be
  152.    sufficient), it also displays the current frame number while
  153.    playing -- however, do not use the buffer option (-b) in
  154.    this case, because the displayed frame numbers will be
  155.    inaccurate.
  156.  
  157.  
  158. OPTIONS
  159. -------
  160.  
  161. The -s and -n options have already been described in the
  162. section "assemble mode", see above.
  163.  
  164. -o outputfile
  165.  
  166.    Use this option to specify the output file name.  You can
  167.    also specify a dash ("-o -") to write to standard output.
  168.    The position of the -o option does not matter.  If no -o
  169.    option is used, no output file will be produced.
  170.  
  171. -v
  172.  
  173.    Increase the verbosity level.  The default level is 0 (which
  174.    means to stay silent except for errors).  Every time you use
  175.    The -v option, the verbosity level is increased by 1.  The
  176.    highest useful level is probably 3 (-vvv), which causes
  177.    mp3asm to explain in more detail what it is currently doing.
  178.    Level 4 or more can produce a whole lot of mostly irrelevant
  179.    information, which is normally useless (and might be even
  180.    confusing).
  181.  
  182.  
  183. REFERENCES
  184. ----------
  185.  
  186. mpg123 is a free, portable MPEG audio player/decoder for Unix.
  187. For more information, visit the following web page, which also
  188. contains a link to the latest version of mp3asm:
  189.  
  190.    http://mpg.123.org/
  191.  
  192. If you are interested in technical details about MPEG audio
  193. files or MPEG compression in general, please refer to the MPEG
  194. standard documents:
  195.  
  196.    IS11172-3 (MPEG 1.0)
  197.    IS13818-3 (MPEG 2.0)
  198.  
  199. They are published by the International Standards Organization
  200. and can be ordered from your local ISO representation.  They
  201. might also be available from larger libraries.  Note that I
  202. don't have the time to answer technical questions related to
  203. the ISO documents.
  204.  
  205.  
  206. 5-Oct-1997
  207. Oliver Fromme  <olli@fromme.com>
  208.  
  209.